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(continued) 




What is new 



• SmartPtr objects can accept different pointer types - d etails 

• Passing a SmartPtr object as function parameter or function result is as efficient as passing an integer value or 
regular pointer - details. 



Introduction 



The SmartPtr class is a generic wrapper that encapsulates pointers. It keeps track of the total number of reference counts 
and performs garbage collection when the pointed object is no more referenced by any "pointer". In addition SmartPtr can 
do Object Level Thread Synchronization for pointed objects. This means that calling the members of the pointed object is 
enclosed in Windows critical section and only one thread at a time can use the object. 

SmartPtr stores reference counter and critical section in separate memory block - not in the pointed object. This causes 
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that you don't have to inherit your classes from special base one to be able to use SnnartPtr as a pointer. And one other 
think is that you could use SnaartPtr to point objects of scalar types - int, short, long, double .... 

SmartPtr is implemented as a template class. Because it has three template parameters It is annoying to specify all of 
them each time. This is the reason I have defined three additional template classes inherited from SmartPtr with 
appropriate default template parameters to get three diferent behaviours: 

• Reference Counting Garbage Collection - SmartPtr will free dynamically allocated memory automatically. 

• Synchronized Access without Reference Counting Garbage Collection - SmartPtr will perform only Thread 
synchronization. You should free dynamically allocated memory in your own. 

• Synchronized Access with Reference Counting Garbage Collection - SmartPtr will perform thread 
synchronization and will free dynamically allocated memory for you. 

These are the classes: 
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All of these classes are equal in their implementation. The different behaviour is achieved via different 
default template parameters. You could use any of these four classes to get any of the three behaviours 
but then you should specify all parameters. 

The following classes are used inside the SmartPtr implementation and SHOULD NEVER be used 
directly. 

• CRefCountRep 

• CSyncAccessRep 

• CSyncRefCountRep 

• CSyncAccess 

Examples of how to use SmartPtr 

You should include the file SmartPtr.h in your project, 

I usually include this line in my SidAtx.b file. 

j^include "Smart:?t:r . h" 



Let's have a class CSomething 

L Reference Counting Garbage Collection on CSomething class 



class 



CSomething { 
CSomethino () ; 
-CSomething () ; 

void doO ; 
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typedef RefCountPtr LPSO^lETHiNG; 

vo i d Te s t Func t ( ) { 

LPSOMETHING pi ^. new CSomething; 

LPS0METHiNC4 p2 ^ pi; 

ii: ( pi NULL ; { 

p5">do() ; 
pi - NULL; 

]// Here the object pointed bv p2 WiLL BE destroved automatically 
////////////////////////////////////// 



2. Object Level Thread Synchronization for objects of CSomething 



claj^js CSomethina { 
CSomet:.hina() : 
•^CSomething 0 ; 



void do ( ) ; 

}; 

typedel: SyacPtr LPSOMETHING; 

void TeBtFuncc ( ; { 

LPSOMETHING pi ^ nev? CSomething; 

LPSOMETHING pS - pi; 

ij: { pi .IsNull 0 ) ( 
.... 

StartThread (pi ) ; 

p2">do(); // Synchronized with the other thread 

pi NULL; 

} // Here the object pointed by p2 v;ili NOT be destroyed automatically 

void ThreadFunc ( LPSOMETHING p ) { 

p->do(); // Synchronized with the other thread 

}// Here the object pointed by p v/ill NOT be desjtroyed automatically 
/ / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / 

In this example you will get memory leaks, but the two threads will be synchronized when trying to call 
object's members. It is your care to free dynamically allocated memory. 



3. Object Level Thread Synchronization and Reference Counting Garbage Collection for objects 
of CSomething 

class CSomething { 
CSomethincO" ; 
-CSomething () ; 
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void do () ; 

}; 

t:/ped8f SyncRef Count Ptr LPSOMETHTNG; 

void TestFunctO { 

LPSOMKTHiNG pi ^ nev/ CSomething; 

LPSOMHITHING p2 pi; 

if( pl.TiBNullO ) { 
StartThread ( pi ); 

p2 -->do(}; // Synchronized v/ith trhe other thread 

pi - NULL; 

}// Here the object pointed by p2 WTLL BE destroyed automatically 
// ii: p in ThreadFunc has already released the object 

void ThreadFunc( LPSOMETHING p ) { 

p->do(); // Synchronized v\?ith the other thread 

}// Here the object pointed by p WILL BE destroyed automatically 

// if p2 in TestFunc has alreadv released the object 
////////////////////////////////////7/ 

In this example you will not get memory leaks and the two threads will be synchronized when trying to 
call object's members. You don't have to free dynamically allocated memory. SmartPtr will do it for you. 



How does SmartPtr work? 



The definition of SmartPtr is: 

template , class ACCESS ^- T'^> 

class SmartPtr : public SmartPtrBase { 



}; 

Where Tis the type of the pointed objects, REP is the representation class used to handle the pointers 
md ACCESS is the class used to get thread safe access to the underlying real pointer. 

There is nothing interesting about Reference Counting Garbage Collection. It is a standard 
implementation. The only interesting thing is that the reference counter and the real pointer are stored in 
the representation object instead of the pointed object. 

The more interesting thing is how Object Level Thread Synchronization works. Let's look at the 
definition of SyncPtr class: 

template , class ACCESS ^^^SyncAcceiaia > 
class SyncPtr { 



ACCESS operator --> (} ; 

^ 

Look at the reference operator. It returns object of type ACCESS, which by default is of type 
CSyncAccess. The trick is that if the reference operator returns something different than a real pointer, 
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the compiler calls the operator ->() of the returned object. If it returns again something different than a 
real pointer compiler calls the returned object operator ->(). And this continues till some reference 
operator returns a real pointer like T*. Well, to get object level synchronization I use this behaviour of 
the reference operator. I have defined a class CSyncAccess: 

template 

class CSyncAccess { 



V i r t ua 1 - CSy ncAc c e s s ( ) ; 
T* operator -> (} ; 

} ; 

1 1 1 1 1 1 ' 1 1 1 1 1 1 1 1 1 1 1 1 ^ ^ > I I t t t t I t I I f i I t t t t t i t t I t t t t t t t t t t > t t I t I t I I t t t I t t t t I t t t t I 

i i i I I i i i I i I I i I I i I I f I I I I I I I 1 1 I i I i I I I I I I 1 1 I I I I 1 1 1 I / I I I I I I I 1 1 / / / / / / / / / / / / / / / / / / / 

The representation class used in this scenario has a member of type CRITICAL_SECTION. 

■rerriplate 

claims CSyncAccessRep { 

CR T T T CAI.__SECT T ON m_Cr i. t i. c:a J. S ec t ;i. ori ; 

} : 

/A//////////////////////// 

And now let*s look at the example code: 

typedef Sync?t:r LPSOMETHING; 
LPSOMETHING p - new CSomething; 

p->do 0 ; 

What's going when p->do{) is called? 

1. The compiler calls SyDcPtr: :operator->() which retums object of type CSyncAccess. This object is 
temporary and is stored on top of the stack. In its constructor the critical section object is 
initialized. 

2. The compiler calls ('SyncAccess:operator->() which owns the critical section and thus protects 
other threads to own it and then returns the real pointer to the pointed object 

3. The compiler calls the method do() of the pointed object 

4. The compiler destroys CSyncAccess object which is on the stack. This calls its destructor where 
the critical section is released and other threads are free to own it. 



The good thing about SmartPtr is that pointed objects do not have to be inherited from any special base 
class as in many other reference counting implementations. The reference counter and the real object 
pointer are stored in dinamically allocated objects of types CRefCountRep, CSyncAccessRep and 
CSyncRefCountRep (called representation objects) depending on what kind of SmartPtr we have. These 
objects are allocated and freed by SmartPtr. This approach allows us to have SmartPtr for objects of any 
classes, not only for inherited from special base class. Well, this is the weakness of the SmartPtr too. 
Imagine that you have a piece of code like this: 

LPSOMKTHING p:i ^- new CSornechi ao ; 

CSoniethiinq**' p2 (CSoinething*^ } pi ; 

LPSOMKTHXKG p3 - p2; 

As result, at the end of this piece of code you think you will have pi and p3 point to the same object. 
Yes, they will. But they will have diferent representation objects in pi and p3. So when p3 is destroyed 
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the underlying CSomething object will be destroyed too and pi will point to invalid memory. So I have a 
simple tip: If you use SmartPtr never use real pointers to underlying objects like in the code above. 
But if you want you can still use real pointers when dealing with other objects. 



Let's look at this code: 



LPSOMETHa>jG p.l nev; CSornechinc : 
SonieFunc ( pi ) ; 



void SomeFunc ( CSomething* pSth ) 
LPSOMETKING p3 - pStrh; 



p3 will create its own representation, ie. its own reference counter and when SomeFunc exits, p3 will 
free the memory pointed by pi . Instead of this function definition you'd better define it this way. 

void SoffieFup.ci LPSOMHITKING pSvAi ); 

I talk about these to notify you that calling SmartPtr constructor or operator ~ with T* parameter 
creates new representation object and this will lead to "strange" behaviour of SmartPtr. 

The mentioned above weakness of the SmartPtr behaviour could be solved if we add static table of 
associations - T* <-> CxxxxxRep* and every time SmartPtr gets T* we could search in this table and 
get appropriate CxxxRep object if it is already created. But this will lead to more memory and CPU 
overhead. And since now I think it is better to follow mentioned above rule than overheading. 



SmartPtr is as efficient as regular pointer and integer values. 

Here is a table with some sizeof() results: 



SmartPtr objects have the same size as pointers and int values. So, passing a SmartPtr objects as 
function (method) arguments or returning SmartPtr object as fianction result is as efficient as doing the 
same with regular pointer or int value. 



SmartPtr objects can accept different pointer types. 

SmartPtr class has a non template base class SmartPtrBase, which is made argument of various 
constructors and assignment operators. Thus a code like this is possible to be used 

clatMJ B { 

)■." 

ciaBB A : public B { 
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}; 



class 



Ref CouncPtr 
Ref Count Ptr 
b = a; 



a - nev; A; 
b " a; 



Even this is very good feature in cases where you need a pointer to base class to 
hold objects of inherited classes you may have a code like this 



RefCountPtr 
ReJICouncPtr 



a - nev/ A; 
b = new B; 



SyncPtr c - a; 
a = b; 
a = c; 
c " a; 

c = b; 

And the compiler v/ill not warn you there are implicit t\^e conversions. Note that 
there is no relatior- between class C and class B . 

In fact, SmartPtr implicitly passes underlying representation objects in such 
assignments. The behaviour of the pointer depends on the underlying representation 
object. So, no matter what is the intention of the holder pointer (in the example 
above '-c'* is a synchronization pointer) the pointer behaviour depends on the t^^^e 
of the representation object creator. 

In the example above, after the last line (c - b;), "c" will hold the object 
pointed by ''b", and even '^c'- is declared as synchronization" pointer v;hen it deals 
with its object it will behave as "reference counting" pointer, because the 
original creator is '*b'* which is of such t^-T^e . 

The enclosed demo project is a simple console application and demonstrates 
different situations and usage of SmartPtr. It is created by VC ++ 5,0. SmartPtr. h 
can be compiled v;ith v/arning level 4. 

Downloads 

Download demo project -■ 12 Kb 
IX^vmload source ■• 4 Kb 
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Smart Pointers 



Smart pointers are classes which store pointers to dynamically allocated (heap) objects. They behave 
much like built-in C++ pointers except that they automatically delete the object pointed to at the 
appropriate time. Smart pointers are particularly useful in the face of exceptions as they ensure proper 
destruction of dynamically allocated objects. They can also be used to keep track of dynamically allocated 
objects shared by multiple owners. 

Conceptually, smart pointers are seen as owning the object pointed to, and thus responsible for deletion 
of the object when it is no longer needed. 

The header boost/smait jtr. hpp provides four smart pointer template classes: 



1 1 scoped ntr ; j Sirr5)le sole ownership of single objects . 

i 1 scoped array ; j Simple sole ownership of arrays. \ \ 

\ \ shared ptr ; j Object ownership shared among multiple pointers \ \ 



These classes are designed to complement the C++ Standard Library auto_ptr class. 

They are examples of the "resource acquisition is initialization" idiom described in Bjame Stroustrup*s 
"The C++ Programming Language", 3rd edition, Section 14,4, Resource Management. 

A test program ( smart jtr test . cpp ) is provided to verify correct operation. 

A page on SmartXoMeiXiniimgs will be of interest to those curious about performance issues. 



These smart pointer classes have a template parameter, t, which specifies the type of the object pointed 
to by the smart pointer. The behavior of all four classes is undefined if the destructor or operator delete 
for objects of type t throws exceptions. 



Several functions in these smart pointer classes are specified as having "no effect" or "no effect except 
such-and-such" if an exception is thrown. This means that when an exception is thrown by an object of 
one of these classes, the entire program state remains the same as it was prior to the function call which 
resulted in the exception being thrown. This amounts to a guarantee that there are no detectable side 
effects. Other functions never throw exceptions. The only exception ever thrown by functions which do 
throw (assuming t meets the Common requircmeiits) is std: :bad_aiioc , and that is thrown only by 
functions which are explicitly documented as possibly throwing std: :bad_aiioc . 



; j shared array i j Array ownership shared among multiple pointers, \ \ 



Common requirements 



Exception safety 
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Exception-specifications 

Exception-specifications are not used; see exception-specification rationale . 

All four classes contain member functions which can never throw exceptions, because they neither throw 
exceptions themselves nor call other functions which may throw exceptions. These members are 
indicated by a comment: // never throws . 

Functions which destroy objects of the pointed to type are prohibited fi-om throwing exceptions by the 
Common requirements . 

History and acknowledgements 

November, 1999. Darin Adler provided operator =, operator !=, and std::swap and std::less 
specializations for shared types. 

September, 1999. Luis Coelho provided shared_ptr::swap and shared_array::swap 

May, 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a number of 
suggestions resulting in numerous improvements. See the revision history in smart ptr .hpp for the 
specific changes made as a result of their constructive criticism. 

Oct, 1998. In 1994 Greg Colvin proposed to the C-1-+ Standards Committee classes named auto_ptr and 
counted_ptr which were very similar to what we now call scoped_ptr and shared_ptr. The committee 
document was 94-168/N0555, Exception Safe Smart Pointers. In one of the very few cases where the 
Library Working Group's recommendations were not followed by the full committee, countedjtr was 
rejected and surprising transfer-of-ownership semantics were added to auto-ptr. 

Beman Dawes proposed reviving the original semantics under the names safejtr and countedjtr at an 
October, 1998, meeting of Per Andersson, Matt Austem, Greg Colvin, Sean Corfield, Pete Becker, Nico 
Josuttis, Dietmar Kiihl, Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four 
class names were finalized, it was decided that there was no need to exactly follow the std::auto_ptr 
interface, and various function signatures and semantics were finalized. 

Over the next three months, several implementations were considered for shared jtr, and discussed on 
the boost.org mailing Hst. The implementation questions revolved around the reference count which must 
be kept, either attached to the pointed to object, or detached elsewhere. Each of those variants have 
themselves two major variants: 

• Direct detached: the shared_ptr contains a pointer to the object, and a pointer to the count. 

• Indirect detached: the shared_ptr contains a pointer to a helper object, which in turn contains a 
pointer to the object and the count. 

• Embedded attached: the count is a member of the object pointed to. 

• Placement attached: the count is attached via operator new manipulations. 

Each implementation technique has advantages and disadvantages. We went so far as to run various 
timings of the direct and indirect approaches, and found that at least on Intel Pentium chips there was 
very little measurable difference. Kevlin Henney provided a paper he wrote on "Counted Body 
Techniques." Dietmar Kiihl suggested an elegant partial template specialization technique to allow users 
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to choose which implementation they preferred, and that was also experimented with. 

But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage users", and in the end 
we choose to supply only the direct implementation. 

See the Revision History section of the header for further contributors. 



Revised 27 Jul 2000 

© Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use, modify, sell and distribute 
this document is granted provided this copyright notice appears in all copies. This document is provided 
"as is" without express or implied warranty, and with no claim as to its suitability for any purpose. 
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// Contents: 
// 

// Definition of countable_ptr template class and its member functions. 

// countablej>tr implements a reference counted smart pointer for pointers to 

// types that satisfy countable requirements (defined below) . 

// 

// The code demonstrates a generalised implemention of the Counted Body idiom 

// (aka Attached Counted Handle/Body idiom) . The benefit of an approach based 

// on generic programming is that the requirements for counting are separated 

// from the implementation mechanism for counting. This open approach means 

// that countable_ptr is suitable for a wide variety of different 

// implementations, and may adapt to existing ones, rather than requiring a 

// new smart pointer type for each strategy. 
// 

// The code is in many ways a traditional implementation of the Counted Body 

// idiom in that it is intrusive, ie countability is acquired explicitly and 

// statically by derivation for a given class. This means that the reference 

// count is explicitly a part of objects even if it is unused (eg in the case 

// of composite members or auto variables) , and that only classes over which 

// you have control can use it. However, by satisfying the countability 

// requirements for count able__ptr no new smart pointer class is required to 

// use classes derived from countability. 
// 

// History: 
// 

// Initial version created by Kevlin Henney, kevlin@acm.org, January 1998. 
// 

// Permissions: 
// 

// Copyright Kevlin Henney, 1998. All rights reserved. 

// 

// Permission to use, copy, modify, and distribute this software for any 

// purpose is hereby granted without fee, provided that this copyright and 

// permissions notice appear in all copies and derivatives, and that no 

// charge may be made for the software and its documentation except to cover 

// cost of distribution. 

// 

// This software is provided "as is" without express or implied warranty. 
// 

// Notes: 
// 

// As there is no requirement that a countable type must be a class, typename 

// is used to introduce type parameters rather than class. If your compiler 

// does not yet support this use of typename, you can replace it with class. 

// 

// For practical reasons the global, rather than a named namespace, has been 

// used to hold the contents of this header. In future the use of a separate 

// namespace is preferred and recommended. 
// 

// This code has been written to conform to standard C++ (in final draft 

// status at the time of writing) . It has been compiled successfully using 

// the operational subset of standard features implemented by Microsoft 

// Visual C++ 5.0. 

#ifndef COUNTABLE_PTR_INCLUDED 
#define COUNTABLE_PTR_INCLUDED 

// 

// Description: 
// 

// Definition of countable_ptr template class, which implements a reference 

// counted smart pointer template for types that satisfy countable 

// requirements. The class is a concrete class not intended as a base class. 
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// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
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// 
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// 
// 
// 
// 
// 
// 



Requirements : 

For a type to be countable it must satisfy the following requirements, 
where ptr is a non-null pointer to a single object (ie not an array) of 
the type, and #function indicates number of calls to function (ptr) : 



expires si on 


return tvne 




aquire (ptr) 


no requirement 


post : acquired (ptr) 


release (ptr) 


no requirement 


pre: acquired (ptr) 
post: acquired (ptr) == 
#acquire > #release 


acquired (ptr) 


convertible to bool 


return: #acquire > #release 


dispose {ptr, ptr) 


no requirement 


pre : ! acquired (ptr) 

post: *ptr no longer usable 



Note that the two arguments to dispose are to support selection of the 
appropriate type safe version of the function to be called. In the general 
case the intent is that the first argument determines the type to be 
deleted, and would typically be templated, while the second selects which 
template to use, eg by conforming to a specific base class. 

In addition the following requirements must also be satisfied, where null 
is a null pointer to the countable type: 

+ = = = = = = = ^ = ^ = ^^ = = = = = = = = + ^ = = = =: = ^ = = = = = = =: = = =. = = = = + = = = = = = = = = = ^^^ = ^ = = = = = = + 

I expression | return type | semantics and notes | 

+ = =: = = = =:= = = = = = = = = = = = = = = + = = = = = = = = = = = ^ = = = ^ = = = = = + = = = === = = = = ^ = = = = = = = = = = ^ + 

I aquire (null) | no requirement | action: none | 
+ + + ^ 

I release (null) | no requirement | action: none | 
+ + + ^ 

I acquired (null) | convertible to bool | return: false | 
+ + + ^ 

I dispose (null, null) | no requirement | action: none | 

Note that there are no requirements on these functions in terms of 
exceptions thrown or not thrown, except that if exceptions are thrown the 
functions themselves should be exception safe. 

In principle these functions may be used on an object independently of 
countable_j)tr, but for a number of reasons this is inadvisable and no 
guarantees (except "you'll be sorry") are made for mixed use (eg using 
both countable_ptr and manual calls of countable functions on an object) . 

Notes : 

The constructor taking a single pointer has been made explicit to prevent 
accidental conversions, but the explicit keyword can be removed if your 
compiler does not support it without affecting the intent. 

For brevity, equality and Boolean operators have been omitted, but are 
simple to add according to the model you wish to support. 

For brevity and portability, member templates for the copy constructor 
and for the copy assignment operator have been omitted. These are simple 
to implement, and are identical in behaviour to the regular copy 
constructor and copy assignment operator [NB: use the get member function 
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// to gain access to the held pointer] . 
// 

// Related member functions (method categories) are placed under their own 

// commented access specifiers. 

// 

// The naming convention adopted is in part based on the standard library, 

// ie get, clear and assign take their names and basic behaviour from the 

// spec for auto_ptr and basic_string . 

// 

template<typename countable_type> 
class countablej)tr 

{ 

public: // construction and destruction 

explicit countable_ptr (count able_type *) ; 
countable_ptr (const countable_j)tr &) ; 
-'COuntable_ptr 0 ; 

public: // access 

countable_type *operator->() const throwO ; 
count able_type &operator* () const throw (); 
count able_type *get ( ) const throwO ; 

public: // modification 

countable_ptr &clear(); 

countable_ptr &assign (countable_type *) ; 
countable_ptr &assign (const countable_ptr &) ; 
countable_ptr &operator= (const countablejptr &) ; 

private: // representation 

countable_type *body; 

}; 

// 

// Description: 
// 

// Definition of countablejptr template class member functions. 
// 

// Notes: 
// 

// Definitions could be placed in a separate header file or, for systems that 

// support separate compilation of templates, in a source file. 

// 

// A number of functions are likely candidates for explicit inlining, but for 
// the purposes of demonstration such an optimisation has not been deemed 
// necessary. 

// 

template<typename countable_type> 

countable_j)tr<countable_type> : : countablejptr (countable_type *initial) 
: body (initial) 

{ 

acquire (body) ; 
template<typename countable_type> 

countable_ptr<countable_type> : : countablejptr (const countable_ptr &other) 
: body (other . body) 

{ 

acquire (body) ; 
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} 

tetnplate<typename countable_type> 
countable_ptr<countable_type> : : -countablejtr ( ) 

{ 

clear () ; 

} 

template<typename countable_type> 

countable_type *countable_ptr<countable_type> :: operator- >( ) const throw () 

{ 

return body; 

} 

template<typename countable_type> 

countable_type &countable_ptr<countable_type> :: operator* ( ) const throw () 

{ 

return *body; 

} 

template<typename countable_type> 

countable_type *countable_j)tr<countable_type> : :get ( ) const throw ( ) 
return body; 

} 

template<typename countable_type> 

countable_j)tr<countable_type> &countable_ptr<countable_type> : : clear ( ) 
return assign (0) ; 

} 

template<typename countable_type> 
countable_ptr<countable_type> & 

countable_ptr<countable_type> :: assign (countable type *rhs) 

{ 

// set to rhs (note that this sequence is self assignment safe) 
acquire (rhs) ; 

countable_type *old_body = body; 
body = rhs; 

// tidy up 

release (old_body) ; 

if (! acquired (old_body) ) 

{ 

dispose (old_body, old body); 

} 

return *this; 

} 

template<typename countable_type> 
countable_ptr<countable_type> & 

countable ptr<countable type> :: assign (const countable ptr &rhs) 

{ 

return assign (rhs .body) ; 

} 

template<typename count able_type> 
count able_ptr< count able_type> & 

countable_j>tr<countable_type> :: operator= (const countable_ptr &rhs) 
return assign (rhs); 

} 
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auto_ptr 



A templatized smart pointer class. 

The autojtr class is used to automatically manage pointers to dynamically created objects. When an 
auto_j)tr is destroyed, the object it points to is also destroyed. Only one auto jtr can own an object at 
a time; copying an auto jtr will transfer the object pointer and ownership of the object to the 
destination autojtr . Therefore, autojptr s can be used safely as retum values for functions. 

Library 

Standards<ToolKit> 
Declaration 

#include <memory> 

template< class T > 
class auto__ptr 



Interface 

Constructor 

explicit auto_ptr( T* ptr ) 
Constructs an auto pointer to manage the object pointed to by ptr (default o ). 
Constructor 

auto_ptr( auto_ptr< T >& other ) 

Constructs an auto pointer and assumes ownership of the object managed by other . 
Destructor 

--autojtrO 

Destroys the auto pointer and the object it manages. 
auto_ptr< T >& operator=( auto_ptr< T > other ) 

Assumes ownership of the object managed by other . If the auto pointer already manages an object, 
destroys the original object first. 

T& operator*() const 

Returns a reference to the auto pointer's managed object. 

-> 

T* operator->() const 

Returns a pointer to the object auto pointer manages. 

get 

T* get() const 

Returns a pointer to the object auto pointer manages, 
release 

T* releaseO 
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Returns a pointer to the auto pointer's managed object and releases ownership. 



Copyright &copyl 994, 1995, 1996 Obi ectSpace, Inc. 
All Rights Reserved - For use by licensed users only. 
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Standard C++ Library Module Reference Guide 

Rogue Wave web site: Home Page | Main Documentation Page 



auto_ptr 



Module: Standard C++ Library Library: General utiirties 



Doei? xiot inherit 
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Local Index 
Members 

auto ptrO Qet() operator*() released 

a uto pt r ref operator auto ptr<Y>() operator-> () reset() 
element type operator auto ptr ref<Y>() operator=() -auto ptrQ 

Summary 

A simple smart pointer class 
Synopsis 

# i nc 1 \xde <v.\e['Aory> 

name-space std { 

teinplate <class X> clanii auto xrtr. ; 

} 

Description 

The class template specialization auto jF>tr holds onto a pointer obtained via new ( ) and then deletes that object 
when the auto_ptr object itself is destroyed. auto_ptr can be used to make calls to operator new ( ) exception-safe. 



lof5 



4/29/04 11:58 AM 



auto_ptr 



http://www.roguewavB.c»rn^siqjpoiVdocs/soiircepro 



The auto _ptr class has semantics of strict ownership: an object may be safely pointed to by only one auto _ptr, so 
copying an auto _ptr copies the pointer and transfers ownership to the destination if the source had already had 
ownership. 



interface 

teirplate <class Y> 8t:nict: .::ut:o_j)t:r__re;: {}; 
tempilate <cla;3:? X> cla-s-?! autc:>_pi:;r { 
publ ic ; 

typedef X elernenl;:_type; 

// con;ittr'act/copy/de:=!l::roy 

explicit .:;Uto_j)tr {X> p 0) throw () ; 

autc:>_ptr (autc:>_ptr<:X>&) throw {) ; 

terr;j)late < class Y> 

autc:>_ptr (autc:>_ptr<Y >&) throw ( ) ; 

auto_j;tr<X>ci operator:^: {auto_j5tr<X>«) throw {) ; 

template <cla:33 Y> 

auto_j;tr<X>o! operator:^: (auto_j)tr<Y>«) throv;() ; 
'-aia1:.o__pt5:* ( ) th]::*ow ( ) ; 

// rnenibers 

X& operator* {) const: t:hrow{) ; 
X* operator -> {) con-st tl:irow(); 

get {) const throw{) ; 
X* release {) throw () ; 
void reset {X* p ^ 0) throw;); 

// conversions 

a u t o_ _p t r ( a u 1:. o __p t r re f < X > ) t rir ow { ) ; 

teiTipiate <class Y> operator airt:o_j5tr_rei:<Y> { ) throw; ) ; 
tetnolate <cla:3s Y:» ooerator auto i:)tr<Y>() trLrow(); 
\ . " 

} 



Struct auto_ptr_ref 

template < class Y> 
struct auto ptr ref ; 

A namespace-scope struct template that holds a reference to an auto _ptr. An auto _ptr_ref can only be 
constructed within an auto _ptr using a reference to an auto _ptr. It prevents unsafe copying. 



Typedef 

typedef X element__type ; 

The type of element pointed to by auto jtr. 



Constructors 

explicit 

a\ito_ptr (X* p "= 0) throw;) ; 

Constructs an object of class auto _ptr<X>, initializing the held pointer to p, and acquiring ownership of that 
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pointer, p must point to an object of class x, a class derived fronn x for which delete p is defined and 
accessible, or p must be a null pointer. 

auto__ptr (auto_ptr<X>& a) throw () ; 

terTiPlcite <Clc:33 Y> 

auto__ptr {ax3to_ptr<Y>iV a) throw {) ; 

Constructs an object of class auto _ptr<X^, and copies the argument a to *this . If a owned the underlying 
pointer, then *t:his becomes the new owner of that pointer. 

For the constructor template, each specialization requires that a pointer to y be implicitly convertible to pointer 

to elernexU; _ t:ype . 

auto_ptr (auto_ptr_ref <X> r) throw () ; 
Constructs an auto jotrfrom an auto _ptr_ref. 

Destructors 

-cTiuto^ptr ( ) throw ( J ; 

Deletes the underlying pointer. 

Operators 

au t o_p t r< X:> & operators: ( <iu. t: o_jp t: r < X> &. a / ■rhrov; ( ; ; 
template <cla3g Y> 

a Vi t o pt r <X > cV operator ^ ( au t:c)__ j? t r < Y > & a ) t: hrcw ( } ; 

Copies the argument a to * this . If a owned the underlying pointer, then *this becomes the new owner of 
that pointer. If *this already owned a pointer, that pointer is deleted first. The argument a is reset to zero. 

For the function template, each specialization requires that a pointer to y be implicitly convertible to pointer to 

elef'!e3:it_type . 

operator* {) c:onBt: t;hrov;{} ; 

Returns a reference to the object to which the underlying pointer points. 

operator->(/ const t:hrow ( ) ; 
Returns the underlying pointer. 

template <cla33 Y> 

oj>erator auto_ptr_ref<y> () throw (); 

Constructs an auto _ptr_ref from *this and returns it. 

te [lip late <Cla:3:3 Y> 

operator auto ptr<Y> {) throwl) ; 

Constructs a new awfo _ptr using the underlying pointer held by * thin . Calls release { ) on * t:hi8 , so 
*thi3 no longer possesses the pointer. Returns the new auto _ptf. 

Member FunctSons 
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X* 

get() const, throw () ; 

Returns the underlying pointer. 

release () throw () ; 

Releases ownership of the underlying pointer and returns that pointer. The -^tYils object is left holding a null 
pointer. 

void 

reset {X* p - 0} t:hrov;'(}; 

Sets the underlying pointer to p. If non-null, deletes the old underlying pointer. 



Example 

// 

// auto Dtr.cDD 
// 

■ffLncIiKie <ios3treatri> // I: or coiit, end! 
#include <n!etnory> // for autoj;>tr 



// A sif-iDle structure, 
class X 

{ 

int i_ ; 

public : 

X (int i) : i_ ii) { 

;=itd::COUt << "X::X (" « i__ << « ;gtd::endl; 



^x 0 { 

3td::COUt << ''X::-X [■» << i__ « << 3td : : endl ; 



int get () const { return i ; } 



int iTiain () 

{ 

// a iirplicitly initialized to 0 (the null pointer) 
3td: :auto_ptr<X> a; 



// Establish a scove . 
if (1) { 

// b will hold a pointer to an X. 
3td: :auto_ptr<X> b (new X (X2345) ) ; 

// a will now be the owner of 
// the underlying pointer, 
a - b; 

} 
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3td::cout << "b destroyed" << 3td::endl; 

// Output the value contained by 
// the underlying pointer. 
#i f ndef ' J^JSTD NO ^NCN CLASS _A^^ 

stdrrcout << c:-->ge*t () << 3td::endl; 

#else 

stdrrcout << (^sj.cjet {) << gtdr.-endl; 

#endif 

// The pointe];:' will be deleted when a i:? destroyed 
/ / on I e.:: V i ng s cope , 
return 0; 

} 

Prograro Oiitpii t : 
X::X (12345) 
b destroyed 
12345 

X::-X [12345] 



Standards Conformance 

ISO/IEC 14882:1998 - International Standard for Information Systems - Programming Language C++, Section 
20.4.5 
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